<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html>

<head>
<title>monitor-enter</title>
<link rel=stylesheet href="opcode.css">
</head>

<body>

<h1>monitor-enter</h1>

<h2>Purpose</h2>

<p>
Acquire the monitor for the indicated object. 
</p>

<h2>Details</h2>

<table class="instruc">
<thead>
<tr>
  <th>Op &amp; Format</th>
  <th>Mnemonic / Syntax</th>
  <th>Arguments</th>
</tr>
</thead>
<tbody>
<tr>
  <td>1d 11x</td>
  <td>monitor-enter vAA</td>
  <td><code>A:</code> reference-bearing register (8 bits)</td>
</tr>
</tbody>
</table>

<h2>Constraints</h2>

<ul>
  <li>
    A must be a valid register index for the current stack frame.
  </li>
  <li>
    Register vA must contain a reference to an object.
  </li>
</ul>
 
<h2>Behavior</h2>

<ul>
  <li>
    An attempt is made for the current thread to acquire the monitor of the
    indicated object. Various results are possible:
    <ul>
      <li>
        If the monitor is not owned by any thread at this point, then the
        current thread becomes owner of the monitor. The entry count of the
        indicated object is set to 1.
      </li>
      <li>
        Otherwise, if the monitor is owned by the same thread that attempts the
        acquiration, then the entry count of the indicated object is increased
        by 1.
      </li>
      <li>
        Otherwise the monitor is owned by a different thread. The current thread
        sleeps until the monitor of the object is released. Once that happens, a
        new attempt to acquire the monitor is made, as described here. There is
        no guarantee that the second attempt (or any subsequent attempt) will be
        successful.
      </li>
    </ul>
  </li>
</ul>

<h2>Exceptions</h2>

<ul>
  <li>
    NullPointerException if vA is null.
  </li>
  <li>
    IllegalMonitorStateException if the entry count exceeds an
    (implementation-dependent) upper bound for recursive monitor entries. Note
    that it is unlikely this bound is ever hit, since for most implementations
    the call stack will overflow before.
  </li>
</ul>

</body>
</html>
